{
    title:  'Building with MakeMe',
    crumbs: [
        { 'Built with MakeMe': 'index.html' },
    ],
}
            <h1>Building with MakeMe</h1>

            <p>This document describes the process to build the software from source using MakeMe.
                First make sure you have read the <a href="overview.html">Building Overview</a> to prepare your build
                environment. </p>

            <p>The procedure for building with MakeMe is the same for all supported platforms.</p>

            <a name="download"></a>
            <h3>Download MakeMe</h3>
            <p>You can download MakeMe from the
            <a href="https://embedthis.com/makeme/download.html">Embedthis MakeMe Download</a> download site.
            Packaged installations are provided for Windows and Mac. For Linux, use the source distribution.
            Read <a href="../start/index.html">Installing MakeMe</a> for details.</p>

            <a id="configuring"></a>
            <h3>Configuring</h3>
            <p>Before building with MakeMe, you need to do a one-time <em>configuration</em> step. This customizes the software to select features, options and third-party packages available on your system. The <em>configure</em> shell script simply invokes <em>me configure</em> and passes all command line options to <em>me</em>.</p>
            <code>me configure</code>

            <h3>Running Configure</h3>
            <p>You may run the configure script with no options to accept the defaults &mdash; this is a good
            starting point:</p>
            <pre class="ui code segment">configure</pre>

            <p>You may also supply options to tailor the build:
            <pre class="ui code segment">
configure --release --without all
</pre>
            <p>The <em>--release</em> switch instructs MakeMe to build an optimized production release.
            The <em>--without all</em> switch will disable non-essential features and components to create
            a minimal build.</p>

            <p>During configuration, MakeMe will create:</p>
            <ul>
                <li>A MakeMe file that specifies the platforms to build named: start.me</li>
                <li>An output products directory for each platform named: build/OS-ARCH-PROFILE</li>
                <li>A MakeMe file for each platform named: build/OS-ARCH-PROFILE/platform.me</li>
                <li>A source header with for the build configuration named: build/OS-ARCH-PROFILE/inc/me.h</li>
            </ul>
            <p>OS is the name of the operating system, ARCH is the name of the cpu architecture and PROFILE
            is the build profile name, typically "debug" or "release". For example: linux-x86-debug.</p>

            <p>The generated MakeMe files are readable Javascript files that contain the settings to control the build
            when MakeMe is run. When compiling, source code may include the <em>me.h</em> header to read the
            MakeMe configuration.</p>

            <h2>Configure Options</h2>
            <p>The tables below describe the key configuration options.
            <h3>Basic Configure Options</h3>
            <table title="options" class="ui table Segment">
                <thead>
                    <tr>
                        <th class="four wide">Option</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td>--debug</td>
                    <td>Build a debug build. This builds a development, non-optimized build with debug symbols.</td>
                </tr>
                <tr>
                    <td>--help</td>
                    <td>Display the <em>me</em> program usage help.</td>
                </tr>
                <tr>
                    <td class="nowrap">--set KEY=VALUE</td>
                    <td>Set the value of a property in the MakeMe <em>settings</em> collection. For example: "--set
                        mpr.tracing=false".</td>
                </tr>
                <tr>
                    <td>--quiet, -q</td>
                    <td>Run quietly without progress trace.</td>
                </tr>
                <tr>
                    <td>--release</td>
                    <td>Build a release build. This builds an optimized, production-ready build of the software.</td>
                </tr>
                <tr>
                    <td>--verbose, -v</td>
                    <td>Run verbosely and emit more detailed progress trace.</td>
                </tr>
                </tbody>
            </table>
            <h3>Cross Compiling</h3>
            <table title="types" class="ui table Segment">
                <thead>
                    <tr>
                        <th class="four wide">Option</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td class="nowrap">--platform OS-ARCH-PROFILE</td>
                    <td><p>Specify the target platform for which to build. For example "-platform linux-arm-debug". Supported operating systems are: freebsd, linux, macosx, vxworks and windows. Supported architectures are: arm, mips, ppc, x64 or x86.</p> 
                    <p>If the -platform option is omitted, the local system is added as the target platform. You may use the 'local' alias to indicate the local platform.  Multiple platforms may be specified. </p> 
                    <p>The ARCH component may specify a CPU instance to tune for. The CPU setting is used in a -DCPU=VALUE compiler define. For example: "-platform linux-arm:arm7tdmi-debug".</p> 
                    <p>NOTE: the platform switch is not a typical configure --host argument. i.e. The second component is a system architecture and not a distribution name.</p>
                    </td>
                </tr>
            </tbody>
            </table>
            <h3>Feature Options</h3>
            <table title="options" class="ui table Segment">
                <thead>
                    <tr>
                        <th class="four wide">Option</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td class="nowrap">--without all</td>
                    <td>Disable all non-essential possible packages.</td>
                </tr>
                <tr>
                    <td class="nowrap">--set tune=MODE</td>
                    <td>Tune the build to optimize for "size", "speed". You can also select "balanced" for a balance
                    between speed and size. (Default is size).</td>
                </tr>
                </tbody>
            </table>
            <h3>Optional Packages</h3>
            <table title="packages" class="ui table Segment">
                <thead>
                    <tr>
                        <th class="four wide">Option</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td class="nowrap">--with PACKAGE[=dir]</td>
                    <td>Specify if a PACKAGE should be included in the build. The optional directory is the path to
                        the source distribution of the package. If the directory is omitted, <em>me</em> will search the
                        local system for the package in well known places.</td>
                </tr>
                <tr>
                    <td>--without PACKAGE</td>
                    <td>Do not include the PACKAGE in the build.</td>
                </tr>
                </tbody>
            </table>
            <h3>Example Use</h3>
            <pre class="ui code segment">
configure --with openssl=/usr/src/openssl
</pre>
            <a id="building"></a>
            <h2>Building with MakeMe</h2>
            <p>After configuring, you may proceed to build the source code by typing:</p>
            <pre class="ui code segment">me</pre>

            <h3>Packages</h3>
            <p>For a list of the available packages on your system that can be selected via configure, run
            <pre class="ui code segment">configure --help</pre>
            <p>This will display the MakeMe command options followed by a list of configurable features and components.</p>

            <p>You may also find additional packages for download from the
            <a href="https://embedthis.com/catalog/">Pak Catalog</a>. These are packages that can be installed via the
            <a href="https://embedthis.com/pak/">Pak</a> program. Once installed, configure can be run to enable the
            package.</p>

            <h3>Environment Variables</h3>
            <p>When cross compiling, certain environment variables may be passed to the configure script and on to
            <em>me</em> to configure the compiler and linker paths and flags. See more details below
                in the <a href="#cross">Cross Compiling</a> section.</p>
            <table title="env" class="ui table Segment">
                <thead>
                    <tr>
                        <th>Variable</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td>AR</td>
                    <td>Path to the archiver program to use to archive libraries for the target system.</td>
                </tr>
                <tr>
                    <td>CC</td>
                    <td>Path to the C/C++ compiler to use to compile for the target system.</td>
                </tr>
                <tr>
                    <td>CFLAGS</td>
                    <td>Compiler control flags.</td>
                </tr>
                <tr>
                    <td>DFLAGS</td>
                    <td>Compiler preprocessor defines.</td>
                </tr>
                <tr>
                    <td>IFLAGS</td>
                    <td>Include directory options.</td>
                </tr>
                <tr>
                    <td>LD</td>
                    <td>Path to the linker program to link objects for the target system.</td>
                </tr>
                <tr>
                    <td>LDFLAGS</td>
                    <td>Linker flags. E.g. -Ldir to specify a non-standard directory for libraries.</td>
                </tr>
                <tr>
                    <td>VSINSTALLDIR</td>
                    <td>Directory to the version of Visual Studio to use. By default, MakeMe will use the most recent installed version.</td>
                </tr>
                <tr>
                    <td>WIND_BASE</td>
                    <td>Directory to the version of WindRiver VxWorks. By default, MakeMe will use the most recent installed version of the same architecture as specified platform architecture.</td>
                </tr>
                </tbody>
            </table>
            <h2>Examples</h2>
            <p>Here are some useful configure command options.</p>
            <p>To configure to build with the <em>ccarm</em> compiler.</p>
            <code>CC=/opt/bin/ccarm ./configure</code>

            <p>To configure for building outside a source tree. This supports building from source from a
                read-only file system.</p>
            <code>configure --configure /path/to/source</code>

            <p>To configure for a debug build with debug symbols:</p>
            <code>configure --debug</code>

            <p>To configure without TLS/SSL:</p>
            <code>configure --without ssl</code>

            <p>To configure using OpenSSL from a specific source location:</p>
            <code>configure --with openssl=/path/to/openssl-source</code>

            <p>To configure to build for 32-bit X86 (when on a 64-bit system):</p>
            <code>configure --platform linux-x86-debug</code>

            <p>To display all configure options, use <em>configure --help</em>. This is the example output for the
Appweb product.</p>
<pre class="ui code segment">configure --help
Usage: me [options] [targets|goals] ...
  Options:
  --benchmark                              # Measure elapsed time
  --configure /path/to/source/tree         # Configure product
  --configuration                          # Display current configuration
  --continue                               # Continue on errors
  --debug                                  # Same as --profile debug
  --deploy directory                       # Install to deploy directory
  --depth level                            # Set test depth level
  --diagnose                               # Emit diagnostic trace
  --dump                                   # Dump the full project
  --endian [big|little]                    # Define the CPU endianness
  --file file.me                           # Use the specified me file
  --force                                  # Override warnings
  --gen [make|nmake|sh|vs|xcode|main|start]# Generate project file
  --get field                              # Get and display a me field value
  --help                                   # Print help message
  --import                                 # Import standard me environment
  --keep                                   # Keep intermediate files
  --log logSpec                            # Save errors to a log file
  --more                                   # Run output through more
  --nocross                                # Build natively
  --overwrite                              # Overwrite existing files
  --out path                               # Save output to a file
  --platform os-arch-profile               # Build for specified platform
  --pre                                    # Pre-process a source file to stdout
  --prefix dir=path                        # Define installation path prefixes
  --prefixes [debian|opt|embedthis]        # Use a given prefix set
  --profile [debug|release|...]            # Use the build profile
  --quiet                                  # Quiet operation. Suppress trace
  --rebuild                                # Rebuild all specified targets
  --reconfigure                            # Reconfigure with existing settings
  --release                                # Same as --profile release
  --rom                                    # Build for ROM without a file system
  --set [feature=value]                    # Enable and a feature
  --sets [set,set,..]                      # File set to install/deploy
  --show                                   # Show commands executed
  --static                                 # Make static libraries
  --unicode                                # Set char size to wide (unicode)
  --unset feature                          # Unset a feature
  --version                                # Display the me version
  --verbose                                # Trace operations
  --watch [sleep time]                     # Watch for changes and rebuild
  --why                                    # Why a target was or was not built
  --with NAME[=PATH]                       # Build with package at PATH
  --without NAME                           # Build without a package

Feature Selection:
    --set ejs.db=value                     # Enable database support, ejs.db (true|false)
    --set ejs.mail=value                   # Enable mail support, ejs.mail (true|false)
    --set ejs.mapper=value                 # Enable database mapper support, ejs.mapper (true|false)
    --set ejs.tar=value                    # Enable tar support, ejs.tar (true|false)
    --set ejs.template=value               # Enable template support, ejs.template (true|false)
    --set ejs.web=value                    # Enable web support, ejs.web (true|false)
    --set ejs.zlib=value                   # Enable zlib support, ejs.zlib (true|false)
    --set http.pam=value                   # Enable Unix Pluggable Auth Module (true|false)
    --set http.webSockets=value            # Enable WebSockets (true|false)
    --set mpr.logging=value                # Enable application logging (true|false)
    --set configFile=value                 # Path of the appweb.conf file
    --set serverRoot=value                 # Home directory for the server

Components (--with NAME, --without NAME):
    cgi                                    # Common Gateway Interface Module
    dir                                    # Directory Listing Module
    ejs                                    # Embedthis Ejscript Javascript Language
    esp                                    # Embedthis ESP, the amazingly fast C-Language web framework
    mdb                                    # Embedthis MDB Database
    openssl                                # OpenSSL
    php                                    # PHP Web Framework
    sqlite                                 # SQLite Library
    ssl                                    # Secure Socket Layer Interface (OpenSSL)
    vxworks                                # VxWorks SDK
    winsdk                                 # Windows SDK
    zlib                                   # Zlib Library
</pre>

            <h3>Useful MakeMe options and targets</h3>
            <p>Here are some useful MakeMe examples:</p>
            <pre class="ui code segment">me --show     # Show actual commands while building
me --why      # Show why each target is or is not being built
me dump       # Dump the combined MakeMe configuration in one file
me rebuild    # Rebuild all targets
me clean      # Clean all built targets
me rebuild    # Rebuild all targets
me install    # Install the built software locally
me help       # Show MakeMe usage</pre>

            <a name="static"></a>
            <h2>Static Linking</h2>
            <p>On some platforms, it may be necessary to statically link the software. The default MakeMe configuration
            will build using shared libraries. This is so that software can dynamically load modules at run-time.
            It is generally recommended that you use dynamic linking, however,
            if you must statically link, run configure with the
            <i>--static</i> option and then rebuild.</p>
<pre class="ui code segment">
configure --static
me
</pre>

            <a id="installing"></a>
            <h2>Installing</h2>
            <p>You can install the newly built software via <em>me</em>:</p>
            <pre class="ui code segment">sudo me install</pre>
            <p>You can remove by:</p>
            <pre class="ui code segment">
sudo me uninstall
</pre>
            <a id="cross"></a>
            <h2>Cross Compiling</h2>
            <p>To build a product for platform different to that of the local system is called <em>cross compiling</em>. Sometimes this compiling is just for a different instruction set (say x64 instead of x86). Other times, it is for a completely different operating system and/or CPU architecture. </p>

            <p>MakeMe supports cross compiling via the <em>configure -platform PLATFORM</em> option. This adds a platform to the list of platforms to be made. Multiple platforms may be specified and the 'local' platform alias may be used for the local development platform.</p>

            <h3>Specifying the Target Platform</h3>
            <p>A platform specification is of the form OS-ARCH-PROFILE, where the supported operating systems are: freebsd, linux, macosx, vxworks and windows. The ARCH field is one of arm, mips, ppc, x64 or x86. X64 is the AMD/Intel 64-bit instruction set and x86 is the Intel X86 Pentium instruction set. You may also use i386 or i686 for specific Intel X86 instruction sets.</p>

            <p>The ARCH componenty may contain a specific CPU to tune for. This is specified as a <em>:CPU</em> suffix to the ARCH field. Some operating systems such as VxWorks, require a CPU specifier. For example:</p> 
            <code>me --platform vxworks-arm:arm7tdmi-debug -configure .</code>

            <p>This will create a vxworks-arm/platform.me configuration file and a <em>start.me</em> that references it. The platform switch does not need to be restated after configuration and will be ignored.</p>

            <p>Note the configuration options apply to the preceding platform. If no preceding platform, the option applies
            to the local platform. For example:</p>
            <code>configure -with ejscript -platform linux-arm-debug -without ejscript</code>
            <p>This will build with the Ejscript package for the local development system, and without Ejscript for the target.</p>

            <h3>Building 32-bit Applications</h3>
            <p>Some products require local building to make the tools that are required to build for a target platform. These products add a "platforms: ['local']" property to their settings collection in the <em>main.me</em> file. This automatically adds the local platform to the platforms list and is the same as adding <em>--platform local</em> on the command line when configuring.</p>

            <p>If your local system can execute binaries for the specified platform, MakeMe will suppress adding an extra pass for the local system. For example: if you want to build a Windows 32-bit application on a Windows 64-bit system, you can specify <em>--platform windows-x86</em>. MakeMe will realize that your system can also execute 32-bit binaries and will suppress also building for 64-bit.</p>

            <h3>Environment Variables</h3>
            <p>When compiling, you may need to inform <b>configure</b> about your cross-compilation tool chain and where it is located.  MakeMe will do its best to discover the installed SDKs and cross tool chain and will look in well known directories to locate the compiler, linker, libraries and other required tools. If MakeMe cannot locate the tool chain, you can supply the tool chain details via environment variables.</p>

            <p>Use the variables AR, CC and LD to specify the path to the archiver, compiler and linker tools. Use CFLAGS to provide compiler flags, DFLAGS for pre-processor definitions, IFLAGS for compiler include paths and LDFLAGS for linker flags. If these flags are provided to MakeMe when building, they apply to that run only. If the flags are provide when configuring, they are saved in the generated platform build file and apply to all subsequent runs. For example:</p>
            <code>CC=/path/to/compiler CFLAGS=-w configure</code>

            <p>Note that on Unix systems, the compiler is used for linking.</p>

            <p>Here is a cross-compilation <b>configure</b> command line to create a debug build for Linux on ARM7 using a specific compiler version.</p>
            <pre class="ui code segment">
CC=/opt/bin/cc.exe \
CFLAGS=-I/opt/include \
./configure --debug --platform linux-arm:arm7tdi-debug
</pre>

            <h3>Specifying Compiler and SDK Versions</h3>
            <p>By default, MakeMe will use the latest version of a compiler to build an application. However, when building for Windows or VxWorks, you can force MakeMe to use a specific version of Visual Studio or VxWorks by setting the VSINSTALLDIR and WIND_BASE environment variables.</p>

            <p>For example: if you have Visual Studio 2013 (12) and Visual Studio 2015 (14) installed, you can force MakeMe to build with Visual Studio 2013 by setting the <em>VSINSTALLDIR</em> environment variable. This is most easily done by running the Visual Studio <em>vcvarsall.bat</em> script supplied with Visual Studio.</p>

            <code>"c:\Program Files (x86)\Microsoft Visual Studio 12.0 VC\vcvarsall.bat" x86
configure
make</code>
            <p>If building Windows using Cygwin, you can pass the VSINSTALLDIR variable directly into configure.</p>
            <code>VSINSTALLDIR="c:/Program Files/Microsoft Visual Studio 12.0" ./configure</code>

            <h3>VxWorks</h3>
            <p>Before building for VxWorks, you must define the WIND environment variables via the WindRiver <em>wrenv.sh</em> script provided with VxWorks. This defines the WIND_BASE, WIND_HOST_TYPE and other required environment variables.</p>
            <p>The command below runs wrenv.sh and defines the WIND variables in the current shell's environment.</p>
            <code>eval `/path/to/WindRiver/wrenv.sh -p vxworks-6.8 -o print_env -f sh`</code>
            <p>Once defined, you can invoke configure.</p>
            <code>configure --platform vxworks-x86</code>

            <h2>Create an Installable Release</h2>
            <p>After building, MakeMe can create installable packages of the software:</p>
            <pre class="ui code segment">me package</pre>
            <p>The release packages are placed under the <em>build/*/img</em> directory.</p>

           <h2>Deploying</h2>
            <p>If you are embedding into another application or installing to a target device, you can deploy the
            required software files to a staging directory.</p>
            <pre class="ui code segment">me --sets core,lib deploy /tmp/deployed</pre>
            <p>This will copy the core and library files to the <em>deploy</em> directory under the platform
            output directory.</p>
